Loan Origination APIs

These endpoints cover application intake, automated assessment, and bank decisioning for SME merchant loans.

Authentication

All requests require:

Authorization: Bearer demo-credify-token

1. Create Loan Application

Endpoint

POST /api/v1/loan-applications

Description

Create a new loan application for a merchant from the Credify merchant dataset.

Sample request

{
  "merchant_id": "MCH-12345",
  "business_name": "Tech Store LLC",
  "requested_amount": 50000.0,
  "loan_purpose": "inventory",
  "monthly_sales_volume": 125000.0,
  "platform_type": "shopify",
  "requested_term_months": 12
}

Sample response

{
  "application_id": "APP-2026-003",
  "merchant_id": "MCH-12345",
  "business_name": "Tech Store LLC",
  "requested_amount": 50000.0,
  "loan_purpose": "inventory",
  "monthly_sales_volume": 125000.0,
  "platform_type": "shopify",
  "requested_term_months": 12,
  "currency": "EGP",
  "status": "submitted",
  "created_at": "2026-04-23"
}

Field	Type	Required	Description
merchant_id	string	Yes	Unique merchant identifier from the Credify merchant dataset
business_name	string	Yes	Merchant legal business name
requested_amount	decimal	Yes	Requested loan amount in EGP
loan_purpose	enum	Yes	inventory, working_capital, expansion, equipment
monthly_sales_volume	decimal	Yes	Average monthly GMV from POS or commerce channels
platform_type	enum	Yes	shopify, woocommerce, amazon_seller
requested_term_months	integer	Yes	Requested duration in months

2. Credit Assessment

Endpoint

POST /api/v1/loan-applications/{application_id}/assess

Description

Run a deterministic credit assessment against the in-memory merchant and application data.

Sample response

{
  "application_id": "APP-2026-001",
  "sales_performance_score": 82.5,
  "business_age_months": 30,
  "default_risk_rating": "low",
  "recommended_amount": 46000.0,
  "recommended_interest_rate": 16.5,
  "assessment_notes": "Strong sales coverage relative to request. Recommend standard approval path."
}

Field	Type	Direction	Description
application_id	string	Request	Loan application reference
sales_performance_score	decimal	Response	Performance score from 0 to 100
business_age_months	integer	Response	Merchant operating age from fake merchant data
default_risk_rating	enum	Response	low, medium, high
recommended_amount	decimal	Response	Suggested lendable amount
recommended_interest_rate	decimal	Response	Suggested APR
assessment_notes	string	Response	Summary lending note for review

3. Loan Approval Decision

Endpoint

PUT /api/v1/loan-applications/{application_id}/decision

Description

Record the final bank decision. Approved decisions create a new loan account immediately in the fake data store.

Sample request

{
  "application_id": "APP-2026-001",
  "decision": "approved",
  "approved_amount": 45000.0,
  "interest_rate": 16.5,
  "term_months": 12,
  "decision_maker_id": "BANK-OFFICER-19"
}

Sample response

{
  "application_id": "APP-2026-001",
  "decision": "approved",
  "approved_amount": 45000.0,
  "interest_rate": 16.5,
  "term_months": 12,
  "rejection_reason": null,
  "decision_maker_id": "BANK-OFFICER-19",
  "loan_id": "LN-2026-002",
  "status": "approved"
}

Field	Type	Required	Description
application_id	string	Yes	Application reference and must match path parameter
decision	enum	Yes	approved, rejected, pending_review
approved_amount	decimal	If approved	Final approved amount
interest_rate	decimal	If approved	Final APR
term_months	integer	If approved	Final loan term
rejection_reason	string	If rejected	Rejection note
decision_maker_id	string	Yes	Bank officer or system identifier